<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <link rel="stylesheet" href="page.css" type="text/css">
  <title>Documentation: Icons and Images</title>
</head>
<body alink="#990033" bgcolor="#ffffff" link="#990033" text="#000000"
 vlink="#990033">
<!---- TOPIC TITLE WITH LOGO--->
<table border="0" cellpadding="cellspacing=2" width="100%">
  <tbody>
    <tr>
      <td><a href="http://www.fox-toolkit.org" target="_top"><img
 src="art/foxlogo_small.jpg" border="0"></a></td>
      <td id="HEADLINE" valign="bottom" width="100%"><b>Documentation:
Icons and Images <a href="icons.html" target="_top" align="left"><font
 size="-2">[Remove Frame]</font></a>
      <br>
      <img src="art/line.gif" height="1" width="100%"></b></td>
    </tr>
  </tbody>
</table>
<p></p>
<!--- TOPIC TITLE WITH LOGO --->
<ul>
  <p>Icons and Images are part an parcel of attractive, user-friendly
Graphical User Interfaces these days.&nbsp; Consequently, considerable
effort has been expended in designing FOX to allow icon- and image-rich
applications to be developed with the greatest ease.<br>
In FOX, Images and Icons are objects that represent picture data.&nbsp;
Images are simple pictures, whereas Icons are pictures with a <i>shape
mask</i> that may be used to effectively mask out a certain area of the
picture, and allow part the background to peek through as if the
picture were transparent in some areas.<br>
Both Icons and Images may have <b>Client</b> <b>side</b> <b><i>pixel
data</i></b> as well as an <b>X Server side</b> <b><i>pixmap</i></b>
representation.&nbsp; The typical application will construct the
client-side pixel data by filling the Icon or Image with a picture,
then create the server-side representation [after contact with the X
Server has been established] by calling i<tt>con-&gt;create()</tt>,
which creates an server side <i>pixmap</i> and uses a call to&nbsp; <tt>icon-&gt;render()</tt>
to fill the pixmap with the pixel data .</p>
  <p>Note that this is a two-step process which is very similar to that
of constructing and creating regular FOX Widgets.&nbsp; This is no
accident.&nbsp; The FOX philosophy is to construct [client-side] data
structures such as Widgets and Icons and Images etc., then with all the
information available, create their X Server side representation in one
fell swoop by calling <tt>app-&gt;create()</tt>.</p>
  <p>When you have given Buttons or Labels or other FOX Widgets icons,
a call to that Widget's <tt>create()</tt> member function will also
automatically call its icon <tt>create()</tt>.&nbsp; To allow icons to
be shared by multiple Widgets, it is specifically allowed to call <tt>create()</tt>
more than once on an icon or image.</p>
  <p>In many cases, after calling an icon's create() member function,
there is no need to keep the client-side pixel data around; thus, FOX
icons will in most cases release the memory taken up by the pixel
data.&nbsp; Should you want to repeatedly change the pixel data,
however, FXIcon and FXImage have an option <b>IMAGE_KEEP</b> to allow
you to hang on to the pixel data in the client.&nbsp; After making
changes to the pixel data, you can call <tt>icon-&gt;render()</tt>
again to render it into the pixmap.</p>
</ul>
<!--- TOPIC TITLE -->
<p>
<table cellpadding="0" cellspacing="2" width="100%">
  <tbody>
    <tr>
      <td id="HEADLINE" valign="bottom" width="100%"><b>Image Formats
Supported
      <br>
      <img src="art/line.gif" height="1" width="100%"></b></td>
    </tr>
  </tbody>
</table>
</p>
<!--- TOPIC TITLE -->
<ul>
  <p>Currently, FOX supports <b>CUR,&nbsp;</b><b>BMP</b>, <b>GIF</b>,
  <b>ICO, </b><b>IFF, </b><b>JPEG</b>, <b>PCX, PNG</b>, <b>PPM,
RAS, RGB, </b><b>TGA, TIFF, XBM, </b>and<b> XPM</b> based icons and
images.&nbsp; The most preferred format is <span
 style="font-weight: bold;">GIF,</span> as it is about 10 times more
compact than <span style="font-weight: bold;">XPM,</span> and about 2
times more compact than BMP.&nbsp; This is of some concern, as
applications may have lots of icons [some analysis of our own
applications revealed than one application's executable had about 1MB
worth of XPM icons; with GIF, this would have been less than a 100kB].</p>
</ul>
<!--- TOPIC TITLE -->
<p>
<table cellpadding="0" cellspacing="2" width="100%">
  <tbody>
    <tr>
      <td id="HEADLINE" valign="bottom" width="100%"><b>Incorporating
Icons and Images into an Application
      <br>
      <img src="art/line.gif" height="1" width="100%"></b></td>
    </tr>
  </tbody>
</table>
</p>
<!--- TOPIC TITLE -->
<ul>
  <p>One crucial problem with icon-rich applications is where to keep
all those icons; obviously, keeping icons in separate files allows
end-users to substitute icons and perhaps change them with an Icon
Editor program.&nbsp; However, such a scenario also poses a
maintainance problem:- software becomes extraordinarily dependent on
specifics of a user installation, and end-users may actually break
software by substituting corrupted icon files by accident, or perhaps
other applications may overwrite them.&nbsp; Another common problem is
the need for end-users to set paths and environment variables.</p>
  <p>To eliminate these problems, the FOX approach is to <b><i>embed</i></b>
all icons and images right into the application's executable.&nbsp;
This is done by simply by compiling the icons into the code in the form
of C data statements, and then linking them in.</p>
  <p>XPM and XBM icons or images can be directly included into the
source code, as these formats are basically just C++ data arrays
already and there is consequently no reason to use reswrap.&nbsp; <br>
XPM is particularly convenient as it allows you to build icons even
without a graphical icon editor. Other image formats need to be
transformed into a C++ data array with a small build-time utility
called <a name="RESWRAP"></a><b><i>reswrap</i></b>, which is provided
in the FOX distribution.</p>
  <p>Reswrap allows you to generate the C/C++ data arrays automatically
from the icons during the build process of your application; simply add
a few rules into your Makefile, or, under VC++, use the reswrap program
in a so-called <em>Utility Project</em>. For example, given as input a
GIF file image such as below:</p>
  <p></p>
  <center><img src="art/bigpenguin.png" height="57" width="48"><br>
Figure 1. Linux Penguin from file <i>bigpenguin.gif</i>.</center>
  <p></p>
  <p>&nbsp;After processing this file, reswrap generates a C data
statement such as:</p>
  <pre>/* Generated by reswrap from file <i>bigpenguin.gif</i> */<br>const unsigned char bigpenguin[]={<br>  0x47,0x49,0x46,0x38,0x37,0x61,0x30,0x00,0x39,0x00,0xf3,0x00,0x00,0xb2,0xc0,0xdc,<br>  ...............................................................................<br>  ...............................................................................<br>  0xf4,0xe0,0x63,0x90,0x7c,0x7d,0x40,0xc5,0x92,0x0c,0x34,0x39,0x41,0x04,0x00,0x3b<br>  };<br></pre>
  <p>This can then be subsequently compiled into an object file, and
linked
in with the executable.&nbsp; To make use of such an icon, FOX supports
deserialization from a <i>memory stream</i>. The icon data above could
be used as follows to create an Icon:</p>
  <pre>FXIcon *tux_icon = new FXGIFIcon(application,bigpenguin);<br></pre>
  <p>Wait! Is that all? Yes it is!&nbsp; This <i>one</i> statement
creates
an icon object, then <i>deserializes</i> the icon data from the GIF
stream
to build the icon's internal pixel data.&nbsp; A subsequent call:</p>
  <pre>tux_icon-&gt;create();</pre>
  <p>Will create an X pixmap, render the icon into it, and subsequently
release
the pixel data after it is no longer needed.&nbsp; If you had created
the
icon with the IMAGE_KEEP option, the pixel data would have been kept
around
for subsequent manipulation by your application, and perhaps repeated
rendering.
To draw the icon in a window, simply:</p>
  <pre>dc.drawIcon(tux_icon,x,y);<br></pre>
  <p>will do the job.</p>
</ul>
<!--- TOPIC TITLE -->
<p>
<table cellpadding="0" cellspacing="2" width="100%">
  <tbody>
    <tr>
      <td id="HEADLINE" valign="bottom" width="100%"><b>Bitmaps
      <br>
      <img src="art/line.gif" height="1" width="100%"></b></td>
    </tr>
  </tbody>
</table>
</p>
<!--- TOPIC TITLE -->
<ul>
  <p>Bitmaps (XBM images) in FOX behave very much like images.&nbsp;
Except, unlike Images which are always 24 bits, and in color, Bitmaps
are only one bit, or blank and white.&nbsp; Typical uses for Bitmaps
are the creation of patterns and stipples, or shape masks against which
other primitives are clipped. <br>
In terms of constructing and using Bitmaps in FOX, it is completely
analoguous:</p>
  <pre>
// Bitmap Data, in XBM Format

#define gray_width 32
#define gray_height 2
static unsigned char gray_bits[] = {0x55, 0x55, 0x55, 0x55, 0xaa, 0xaa, 0xaa, 0xaa};

// Construct a bitmap object
FXBitmap *grayBitmap=new FXBitmap(application, gray_bits, 0, gray_width, gray_height);
  </pre>
  <p>In terms of using Bitmaps for subsequent tiling and stippling
operations,
remember that MS-Windows has certain size limits such patterns;&nbsp;
X-Windows
has no such limit, but presumably smaller patterns are more
efficient.&nbsp;
It is probably a good idea to keep so widths such as 8,16, or 32.</p>
</ul>
<!--- TOPIC TITLE -->
<p>
<table cellpadding="0" cellspacing="2" width="100%">
  <tbody>
    <tr>
      <td id="HEADLINE" valign="bottom" width="100%"><b>Cursors
      <br>
      <img src="art/line.gif" height="1" width="100%"></b></td>
    </tr>
  </tbody>
</table>
</p>
<!--- TOPIC TITLE -->
<ul>
  <p>Cursors can be constructed in FOX to change the shape of the
mouse-cursor.&nbsp;
Constructing Cursors is very similar to constructing Bitmaps, except
that
Cursors comprise two bitmaps, a picture and a shape mask; also, Cursors
have a so-called hot-spot, the point inside the cursor-glyph which is
``pointer
to'' by the mouse. <br>
FOX currently also supports color cursors with an alpha component, i.e.
partially transparent cursors.&nbsp; This is limited to certain
platforms; on platforms where color cursors are not supported, the
color image is thresholded to a simple black/white image with the alpha
channel mapping to fully transparent.&nbsp; Designing your color
cursors with contrasting colors ensures that they will look reasonable
on such platforms.<br>
  </p>
  <p>Besides defining your own ``custom'' cursors, FOX also allows you
to
simply create a ``stock'' cursor, i.e. a cursor whose shape has already
been predefined by the system.
To create a custom Cursor:</p>
  <pre>// Picture bits, in XBM Format<br>#define resize_width 32<br>#define resize_height 32<br>#define resize_x_hot 9<br>#define resize_y_hot 9<br>static unsigned char resize_bits[] = {<br>   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xfc, 0x00, 0x00, 0x00,<br>   ....<br>   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00};<br><br>// Shape bits, in XBM Format<br>#define resize_mask_width 32<br>#define resize_mask_height 32<br>#define resize_mask_x_hot 9<br>#define resize_mask_y_hot 9<br>static unsigned char resize_mask_bits[] = {<br>   0x00, 0x00, 0x00, 0x00, 0xfe, 0x01, 0x00, 0x00, 0xfe, 0x01, 0x00, 0x00,<br>   ....<br>   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00};<br><br><br>  // Resize corner<br>  resizeCursor=new FXCursor(application,resize_bits,resize_mask_bits,resize_width,resize_height,resize_x_hot,resize_y_hot);<br></pre>
  <p>To create a stock Cursor:</p>
  <pre>// Text Cursor<br>IBeamCursor=new FXCursor(application,CURSOR_IBEAM);<br></pre>
  <p>If you define your own Custom Cursors, make sure the size is
exactly
32x32. MS-Windows does not support any other sizes.&nbsp; Also, the
shape
and the picture will have to be the same size.</p>
</ul>
<!--- TOPIC TITLE -->
<p>
<table cellpadding="0" cellspacing="2" width="100%">
  <tbody>
    <tr>
      <td id="HEADLINE" valign="bottom" width="100%"><b>If Icons Look
Funny...
      <br>
      <img src="art/line.gif" height="1" width="100%"></b></td>
    </tr>
  </tbody>
</table>
</p>
<!--- TOPIC TITLE -->
<ul>
  <p>Sometimes, your icons may look funny.&nbsp; This is usually
because FOX Icon routines determine the wrong value for the
transparency color.&nbsp; FOX can handle images with a true
alpha-channel, or images with a special transparency color.&nbsp; The
latter is the more common approach, as many file formats do not support
true alpha channels. <br>
Different image formats guess the transparency color in different ways.
For <b><i>GIF</i></b> Images, FOX uses the following algorithm:</p>
  <ul>
    <li>If a transparent color is found in the GIF file, that color is
used.</li>
    <li>If not, the background color is used.</li>
    <li>If the option IMAGE_ALPHACOLOR is used when constructing the
icon, the specified color is used.</li>
    <li>Finally, if the option IMAGE_OPAQUE is used, the icon is forced
to be non-transparent.</li>
  </ul>
  <p><br>
For <b><i>BMP</i></b> images, there is no background or transparency
color in the image file format; the algorithm is simpler:</p>
  <ul>
    <li>The assumed transparency color is the same as the default GUI
background color, which is FXRGB(192,192,192).</li>
    <li>If the option IMAGE_ALPHACOLOR is used when constructing the
icon, the specified color is used.</li>
    <li>Finally, if the option IMAGE_OPAQUE is used, the icon is forced
to be non-transparent.</li>
  </ul>
  <p>In most cases, you will create your icons simply as below:</p>
  <pre>new FXGIFIcon(app,picture_data);<br></pre>
  <p>In some cases, when you want to override the transparency
color,construct your icons as:</p>
  <pre>new FXGIFIcon(app,picture_data,FXRGB(192,192,192),IMAGE_ALPHACOLOR);<br></pre>
  <p>To create an completely opaque icon:</p>
  <pre>new FXGIFIcon(app,picture_data,0,IMAGE_OPQUE);<br></pre>
  <p>For more information on graphics file formats and their
idiosyncracies,
see&nbsp; the <a
 href="http://www.dcs.ed.ac.uk/%7Emxr/gfx/index-hi.html">Graphics
File Format Web Site</a>.</p>
</ul>
<!--- TOPIC TITLE -->
<p>
<table cellpadding="0" cellspacing="2" width="100%">
  <tbody>
    <tr>
      <td id="HEADLINE" valign="bottom" width="100%"><b>More on Reswrap
      <br>
      <img src="art/line.gif" height="1" width="100%"></b></td>
    </tr>
  </tbody>
</table>
</p>
<!--- TOPIC TITLE -->
<ul>
  <p>The reswrap tool has a number of options to make it convenient to
build
C source and header files automatically from image files as a part of
your
regular project build process.&nbsp; Reswrap is normally invoked as
follows:</p>
  <pre>reswrap [options] [-o[a] outfile]&nbsp; files....<br></pre>
  <p>Invoking reswrap with <tt>-o outfile</tt> will make reswrap write
its output
on the file <b><i>outfile</i></b>.&nbsp; With <tt>-oa outfile</tt>,
reswrap
will append additional data at the end of <b><i>outfile</i></b>.
  <br>
Any number of input files may be specified.&nbsp; Reswrap typically
produces one data statement for each of the input files specified on
the
command line.</p>
  <p>Reswrap understands a few additional options:</p>
  <p><b><i>-h</i></b>
  </p>
  <blockquote>Will print out a summary of the supported options.</blockquote>
  <b><i>-v</i></b>
  <blockquote>Will print out the version number.</blockquote>
  <b><i>-d</i></b>
  <blockquote>Reswrap normally generates its output as hexadecimal
numbers;
the -d option will make reswrap generate decimal numbers.</blockquote>
  <b><i>-x</i></b>
  <blockquote>Forces reswrap to generate hexadecimal numbers [the
default].</blockquote>
  <b><i>-e</i></b>
  <blockquote>Places the storage modifier <b><tt>extern</tt></b> in
front
of the data array, ensuring that the data array can be linked with
other
compilation units.</blockquote>
  <b><i>-i</i></b>
  <blockquote>Instead of a data array statement, reswrap will generate
a
declaration only.&nbsp; For example,</blockquote>
  <pre>reswrap -i bigpenguin.gif<br></pre>
  <blockquote>will produce the output:</blockquote>
  <pre>/* Generated by reswrap from file bigpenguin.gif<br>*/<br>extern const unsigned char bigpenguin[];<br></pre>
  <p>Which you could include as a header file into whichever source
file
needs access to the data.<br>
  <br>
  <b><i>-s</i></b>
  </p>
  <blockquote>This option suppresses comments inserted by reswrap to
indicate
the original file name from which the data statement was generated.</blockquote>
  <b><i>-n name</i></b>
  <blockquote>Instead of taking the filename less the extension,
reswrap
substitutes <i>name</i> for the name of the resource.</blockquote>
  <b><i>-c cols</i></b>
  <blockquote>Uses <i>cols</i> columns instead of the default 16
columns
in the data statements generated by reswrap.</blockquote>
  <b><i>-ppm</i></b>
  <blockquote>Assumes the source file is a Portable Pixmap (ppm)
file.&nbsp;
Reswrap will output a simple rgb array.</blockquote>
Example of using reswrap in your Application's Makefile:
  <p></p>
  <pre>OBJECTS = icons.o myapp.o<br>ICONS = bigpenguin.gif applogo.gif<br>icons.h: $(ICONS)<br> reswrap -e -o icons.h $(ICONS)<br><br>icons.cc: $(ICONS)<br> reswrap -o icons.cc $(ICONS)<br><br>myapp: $(OBJECTS)<br>   gcc -o myapp $(OBJECTS) -lFOX -lm -lSM -lICE -lXext -lX11<br><br>myapp.o: myapp.cc icons.h<br></pre>
  <p>This will cause make to generate two files, <tt>icons.h</tt> and <tt>icons.cc</tt>
which contain the declarations and definitions respectively for all the
reswrapped icons listed in the ICONS variable.</p>
</ul>
<!--- COPYRIGHT -->
<p>
<table cellpadding="0" cellspacing="0" width="100%">
  <tbody>
    <tr>
      <td id="HEADLINE" align="right" valign="top" width="100%"><img
 src="art/line.gif" height="1" width="100%"><font size="-1">
Copyright &copy; 1997-2005 Jeroen van der Zijp</font>
      </td>
    </tr>
  </tbody>
</table>
</p>
<!--- COPYRIGHT -->
</body>
</html>
